<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
        <title>AJ Security/Image captcha</title>
        <meta name="description" content="A Practical Java Web Security Library. Image captcha"/>
        <meta name="keywords" content="security, xss, csrf, captcha, captcha"/>
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
         <link rel="stylesheet" href="https://framework.ajaxjs.com/static/font/font.css" />
        <link rel="stylesheet" href="/asset/main.css"/>
        <link rel="icon" type="image/x-icon" href="https://framework.ajaxjs.com/aj-logo/logo.ico"/>
        <script src="https://framework.ajaxjs.com/static/aj-docs/common.js"></script>
        <script>
            // 获取用户的默认语言
            var userLang = navigator.language || navigator.userLanguage;

            // 检查是否为中文环境（包括简体和繁体）
            if (userLang.startsWith('zh') && location.pathname.indexOf('cn') == -1) {
                 confirm('欢迎！您可以改为访问中文内容。是否继续？') && location.assign('/cn');  // 如果是中文，则弹出提示
            }

            var _hmt = _hmt || [];
            (function() {
              var hm = document.createElement("script");
              hm.src = "https://hm.baidu.com/hm.js?950ba5ba1f1fe4906c3b4cf836080f03";
              var s = document.getElementsByTagName("script")[0];
              s.parentNode.insertBefore(hm, s);
            })();
        </script>
    </head>
    <body>
        <nav>
            <div>
                <div class="links">
                    <a href="/">🏠 Home</a>
                    | ⚙️ Source:
                    <a target="_blank" href="https://github.com/lightweight-component/aj-security">Github</a>/<a target="_blank" href="https://gitcode.com/lightweight-component/aj-security">Gitcode</a>
                    |
                    <a href="/cn">Chinese Version</a>
                </div>
                <h1><img src="https://framework.ajaxjs.com/aj-logo/logo.png" style="vertical-align: middle;height: 45px;margin-bottom: 6px;" /> AJ Security</h1>
                <h3>User Manual</h3>
            </div>
        </nav>
        <div>
            <menu>
                <ul>
                    <li class="selected">
                        <a href="/">Home</a>
                    </li>
                    <li>
                        <a href="/install">Installation & Configuration</a>
                    </li>
                </ul>
                <h3>HTTP Web Security</h3>
                <ul>
                    <li>
                        <a href="/http/http-referer">HTTP Referer Validation</a>
                    </li>
                    <li>
                        <a href="/http/timestamp">Timestamp Encrypted Token Validation</a>
                    </li>
         <li>
                       <a href="/http/paramssign">Parameter Signature</a>
                    </li>
                    <li>
                        <a href="/http/ip-list">IP Whitelist/Blacklist</a>
                    </li>
                    <li>
                        <a href="/http/nonrepeatsubmit">Prevent Duplicate Submission</a>
                    </li>
                </ul>
                <h3>General Web Validation</h3>
                <ul>
                    <li>
                        <a href="/classic/xss">Prevent XSS Attacks</a>
                    </li>
                    <li>
                        <a href="/classic/crlf">Prevent CRLF Attacks</a>
                    </li>
                </ul>

                <h3>Captcha Mechanism</h3>
                <ul>
                    <li><a href="/captcha/img-captcha">Image Captcha</a></li>
                    <li><a href="/captcha/google">Google-based Captcha</a></li>
                    <li><a href="/captcha/cf">CloudFlare-based Captcha</a></li>
                </ul>
                <h3>HTTP Standard Authentication</h3>
                <ul>
                    <li><a href="/auth/http-basic-auth">HTTP Basic Auth</a></li>
                    <li><a href="/auth/http-digest-auth">HTTP Digest Auth</a></li>
                </ul>
                <h3>API Features</h3>
                <ul>
                    <li><a href="/api/limit">Rate Limiting</a></li>
                </ul>
                <h3>Other Practical Features</h3>
                <ul>
                    <li><a href="/misc/desensitize">Field Desensitization</a></li>
                    <li><a href="/misc/encryption-api">API Encryption</a></li>
                    <li><a href="/misc/trace-id">Trace Tracking</a></li>
                </ul>
            </menu>
            <article>
                <h1>Image CAPTCHA</h1>
<p>Image CAPTCHA helps prevent malicious activities such as bot registration and spamming. It is generally recommended to add this protection when performing write operations on public-facing interfaces.</p>
<h2>Usage</h2>
<h3>YAML Configuration</h3>
<pre><code class="language-yaml">security:
  ImageCaptcha: # Image CAPTCHA
    enabled: true
    expireSeconds: 60
</code></pre>
<h2>Configuration</h2>
<p>Create a configuration class and add it to the Spring container. The main purpose is to determine which image generator and caching method to use. For simplicity, we use the JVM's built-in <code>SimpleCache</code> here.<br>
If you want to switch to Redis, you can configure <code>SaveToRam</code>, <code>CaptchaCodeFromRam</code>, and <code>RemoveByKey</code> as shown below.</p>
<pre><code class="language-java">static final SimpleCache RAM = new SimpleCache(); // JVM cache

@Bean
ImageCaptchaConfig ImageCaptchaConfig() {
    ImageCaptchaConfig config = new ImageCaptchaConfig();
    config.setCaptchaImageProvider(new SimpleCaptchaImage());
    config.setSaveToRam(RAM::add);
    config.setCaptchaCodeFromRam(key -&gt; {
        SimpleCache.Item item = RAM.get(key);
        return item == null ? null : item.getValue();
    });
    config.setRemoveByKey(RAM::remove);

    return config;
}
</code></pre>
<h3>Add a Controller</h3>
<p>Add an API endpoint that returns the image CAPTCHA:</p>
<pre><code class="language-java">@Autowired
ImageCaptcha imageCaptcha;

@GetMapping(&quot;/captcha&quot;)
void showCaptcha(HttpServletRequest req, HttpServletResponse response) {
    imageCaptcha.captchaImage(req, response);
}
</code></pre>
<p>The frontend must include a <code>uuid</code> parameter when requesting this endpoint, which serves as the unique identifier for this CAPTCHA generation. It's recommended to pass it via query string, for example: <code>/captcha?uuid=xxx</code>.</p>
<h3>Protect an API</h3>
<p>Add the <code>@ImageCaptchaCheck</code> annotation to the API you want to protect:</p>
<pre><code class="language-java">@PostMapping(&quot;/create_user&quot;)
@ImageCaptchaCheck
boolean createUser(@ModelAttribute User user);
</code></pre>
<p>That's basically all you need. The interceptor will automatically verify the CAPTCHA. If valid, the request proceeds to the business logic; otherwise, an exception is thrown and intercepted.</p>

            </article>
        </div>
        <footer>
            AJ Security, a part of
            <a href="https://framework.ajaxjs.com" target="_blank">AJ-Framework</a>
            open source. Mail:frank@ajaxjs.com, visit
            <a href="https://blog.csdn.net/zhangxin09" target="_blank">my blog(In Chinese)</a>. <br/> <br/> Copyright © 2025 Frank Cheung. All rights reserved.
        </footer>
    </body>
</html>